\documentstyle[fancyheadings,twoside,epsf,indentfirst]{article}
% Vertical sizes
%\vsize=20cm
%\voffset=-2.3cm
%\topmargin=0cm
%\headheight=0.9cm
%\footskip=1cm
%\footheight=0.9cm
%\textheight=16cm
%\headrulewidth 0.01cm
%\footrulewidth 0.0cm
% 0 sizes
%\hsize=30cm
%\hoffset=-4.3cm
%\hoffset=-2.3cm	
%\textwidth=13cm
% Modes
% \special{landscape}
\pagestyle{empty}
\pagestyle{fancyplain}
\newcommand{\tit}[1]{#1}
\rhead[\fancyplain{}{\tit{\leftmark}}]{\fancyplain{}{\tit{\rightmark}}}
\lhead[\fancyplain{}{\tit{\rightmark}}]{\fancyplain{}{\tit{\leftmark}}}
\chead{\hfill}
\lfoot[\fancyplain{}{\tit{\thepage}}]{\fancyplain{}{\hfill}}
\rfoot[\fancyplain{}{\hfill}]{\fancyplain{}{\tit{\thepage}}}
\cfoot{\hfill}
\renewcommand{\sectionmark}[1]{\markboth{#1}{\ }}
\renewcommand{\subsectionmark}[1]{\markright{\ }}
\newcommand{\look}[1]{(Chapter~\ref{#1}, page~\pageref{#1})}
\newcommand{\toindex}[1]{\underline{\bf#1}\index{#1}}
\newcommand{\add}[1]{\symbol{64}}
\newcommand{\ps}[1]{\symbol{37}s}
\newcommand{\twcol}[4]{
\noindent\parbox[t]{#1\textwidth}{#3} \hfill \parbox[t]{#2\textwidth}{#4\hfill}\\
}
\newcommand{\tc}[2]{\twcol{0.49}{0.49}{#1}{#2}}
\newcommand{\tcc}[2]{\twcol{0.49}{0.49}{\toindex{#1}}{#2}}
\newcommand{\ttt}[2]{\bigskip

{\bf#1}

#2}
\newcommand{\ts}[1]{{\underline{\bf#1}}}
\newcommand{\dl}[2]{\parbox[t]{0.4\textwidth}{#1\hfill}\hfill
                    \parbox[t]{0.4\textwidth}{#2\hfill}}
\makeindex
\begin{document} 
\title{\bf\it LIBFTP User's guide}
\author{Oleg Orel}
\date{\today}
\newpage
\maketitle

\section*{LICENSE}

This library is desired for free, non-commercial software creation. 
It is changeable and can be improved. The author would greatly appreciate 
any advises, new components and patches of the existing programs.
Commercial usage is also possible with participation of it's author.

\section*{INTRODUCTION}

The basic orientation of this library is making user's programs which transport
files via TCP/IP network. It contains set of functions, starting from primitive, such as 
opening FTP connection to the server, and finishing by high-level functions, such as functions which retrieve files
 via network, making and closing channels to the server. All functions have 
prototypes in common header file named \toindex{FtpLibrary.h}, 
which must be 
available in standard headers directory. Those prototypes almost fully 
describe orientation and arguments of all functions, but common ideology and library components should be mentioned. 

This library is a client and uses standard FTPD from the other side.

There are problems of errors processing in UNIX including input/output errors. 
The mutual mechanism of value returning of all functions is used in this library.
(EXIT macros, defined in file FtpLibrary.h). This mechanism allows,
 after the definition of the error processing functions, write programs, 
considering the conditions to be ideal.
Data transfer functions have possibility to preset data stream expectation timeout.
When the set time expires, previously set function will be called.

The first function, which should be called for work with library is FtpConnect or FtpLogin. 
They make connection to FTP server and return pointer to FTP date structure.  


\section{The FTP data structure}


\tc{int \toindex{sock}}{--- descriptor of a command channel to the server;}
\tc{FILE *\toindex{data}}{--- pointer to data structure, which describes data channel to the server;}
\tc{int \toindex{errno}}{ --- last returned value. When value is lower than 1, an error occurred;}
\tc{char \toindex{mode}}{--- type of transfer;}
\tc{int ch}{--- help variable. Is used to convert ASCII files;}
\tc{STATUS (*func)()}{---  pointer to an error handler. It is called 
                       when status from the server is bad;}
\tc{STATUS (*debug)()}{--- pointer to a debug handler. Is called from  
                        functions of sending/receiving messages to/from server;}
\tc{STATUS (*IO)()}{--- pointer to Input/Output error handler. Is called when channel to server is broken.}

\section{ Connection/Disconnection with server}

\ttt{STATUS \toindex{FtpConnect}(FTP~**, char~*hostname
\footnote{The name of the host may be symbolic (for example \ts{dxcern.cern.ch}) or numeric (for example \ts{128.141.201.96})}
)}
{
  Makes channel to the server, at the ``hostname'' machine.
  Creates FTP data structure and returns pointer to it. If the procedure \toindex{FtplibDebug}(1)
was previously called, \ts{FtpConnect} calls automatically \ts{FtpDebug} for the \ts{debug mode} to be turned on. 
  \look{debug}.
}
\ttt{STATUS \toindex{FtpUser}(FTP~*, char~*user)}
{
 Sends the name of the user to the server. The connection must be done before it.
}

\ttt{STATUS \toindex{FtpPassword}(FTP~*, char~*password)}
{
 Sends \ts{password} to the server. The function \ts{FtpUser} must be called before it.
}

\ttt{STATUS \toindex{FtpAccount}(FTP~*, char~*acct)}
{
 Sends a name of the account to the server. The name of the account is not standard
 attribute for many systems, so this function is used very seldom.
 The function \ts{FtpPassword} must be called before it.
}

\ttt{
STATUS \toindex{FtpLogin}(FTP~**, char~*hostname, char~*user, char~*password, char~*account)}
{
  Executes functions \ts{FtpConnect}, \ts{FtpUser}, \ts{FtpPassword},
  \ts{FtpAccount} (if necessary)  consistently. If the name of the account is absent, 
  replaces it with the \ts{NULL} value.
}

\ttt{STATUS \toindex{FtpBye}(FTP~*)}
{ Finishes work with the server and closes all channels. 
\footnote{You can see from the description of connect/disconnect functions, that you can create 
more than one connection to servers simultaneously.

}

\section{The debugging} \label{debug} 

There is a possibility to predefine three functions, such as:
\footnote{If the \ts{NULL} value is transferred as a parameter \ts{``function''} to the functions, described below,
the debugging will be turned off.}

\ttt{\toindex{FtpSetDebugHandler}(FTP *,function)}
{  Predefines function of protocol debugging.
   After the function is predefined, it is called with every 
   sending/receiving messages from the server.
   The function, defined as a debug handler must do returns to the calling 
functions (\ts{FtpSendMessage}/\ts{FtpGetMessage}), but can also abort the program. 

}

\ttt{\toindex{FtpSetErrorHandler}(FTP *,function)}
{
   Predefines error handler. If the server's answer means, that the operation is not finished 
 correctly, this function will be called.
   The result code is negative, if an error is occurs.
}
\ttt{\toindex{FtpSetIOHandler}(FTP *,function)}
{
   Predefines handler of Input/Output processing. This function is called, when a connection to the  
   server is broken. For example, when the network or the remote host is down. This handler also is
   called after the  \toindex{timeout} of one character waiting expires.   
}

\ttt{\toindex{FtpDebug}(FTP *)}
{
Turns on all standard debugging functions. 
\tc{\toindex{FtpDebugError}}{--- prints a string, taken from the server, and aborts the program;}
\tc{\toindex{FtpDebugDebug}}{--- prints a string, taken from the server;}
\tc{\toindex{FtpDebugIO}}{--- prints string \ts{strerror(errno)} and aborts the program.}
}

All function for debugging have three arguments:\\
1. Pointer to FTP data structure;\\
2. Last returned value from the server. When errors occur, the value is less than 1;\\
3. Diagnostic string.

\ttt{\toindex{FtplibDebug}(1 or 0)}
{	Turns on/off autostart debug mode, when connection is established.
}

\section{Data transfer procedures from the server}

\ttt{STATUS  \toindex{FtpRetrTimeout}(FTP~*, char~*command, char~*inp, char~*out
\footnote{When the name of the local file is \ts{*STDIN*}, \ts{*STDOUT*}, \ts{*STDERR*}, then the current stream is
redirected to these channels}, long~time)}
{
	Sends a command to the server, if command contains substring \ps, it will be replaced by 
        string \ts{inp}.
	Creates data transfer channel, and copying data from this channel to a local file \ts{out}.
	If during time period \ts{``time''} no characters are obtained from the server, this 
	connection will be closed, and Input/Output error status will be returned.
	When \toindex{timeout}=0, timeout in library level will be turned off, but
	procedures may be aborted by the kernel of TCP/IP, when the kernel's \ts{timeout} expires.  
        \footnote{In different kernels timeout is different}
}

\ttt{\toindex{FtpRetr}(FTP~*, char~*command, char~*inp, char~*out)}
{
 Calls \ts{FtpRetrTimeout}, with turned off \ts{timeout}.
}

\ttt{\toindex{FtpGetTimeout}(FTP~*, char~*inp, char~*out, long~time)}
{
 Transfers file \ts{inp} from the server to the local file \ts{out}, with \ts{timeout=time}.}

\ttt{\toindex{FtpGet}(FTP~*, char~*in, char~*out)}
{
 Calls \ts{FtpGetTimeout}, with turned off \ts{timeout}.

}
\ttt{\toindex{FtpDirectory}(FTP~*, char~*pat\footnote{This is the first argument for \ts{``ls''} command}, char~*out)}
{
 Transfers files listing from the server, described by \ts{pat}, to the local file \ts{out}.
}
\ttt{\toindex{FtpDir}(FTP~*, char~*out)}
{
 Transfers files listing of the current directory from the server to the local file \ts{out}.
}

\section{Data transfer procedures to the server}

\ttt{\toindex{FtpStorTimeout}(FTP~*, char~*command, char~*inp, char~*out, long~time)}
{
  Sends body of the local file \ts{inp} to the server, and stores it in the file \ts{out}.
  The ``time'', is maximum time needed to transfer one character to the server.
}

\ttt{\toindex{FtpStor}(FTP~*, char~*command, char~*inp, char*~out)}
{
  Calls \ts{FtpStorTimeout}, without \ts{timeout}.
}

\ttt{\toindex{FtpPutTimeout}(FTP~*, char~*in, char~*out, long~time)}
{ Transfers data from the local file \ts{inp} to the server and stores it in the file \ts{out}.
}


\ttt{\toindex{FtpPut}(FTP~*, char~*in, char~*out)}
{
 Calls FtpPutTimeout with turned off timeout.
}


\section{Server's files read/write procedures}

This library contains special functions for remote files reading and writing, without precopying
them to local files. The functions, which are described below, do it. After the data channel 
to a remote file is created, it becomes possible to read and write characters using standard Input/Output functions,
or using special functions \ts{FtpRead}/\ts{FtpWrite}, which reorganize stream for standard text file, 
under condition
that the \ts{ASCII} mode is set. \footnote{Of course, such functions as \ts{seek}, \ts{ioctl}, .... 
can not be used.}

\ttt{\toindex{FtpData}(FTP~*, char~*command, char~*param, char~*mode)}
{ Makes data transfer channel, with presending command composed from \ts{command} and \ts{param}. 
The mode must be \ts{``r''} or \ts{``w''}}

\ttt{\toindex{FtpOpenRead}(FTP~*,char~*filename)}
{ Opens file named \ts{filename} for reading on server}

\ttt{\toindex{FtpOpenWrite}(FTP~*,char~*filename)}
{ Creats and opens file named \ts{filename} for writing on server}

\ttt{\toindex{FtpOpenAppend}(FTP~*,char~*filename)}
{ Creats and opens file named \ts{filename} for appending on server}

\ttt{\toindex{FtpOpenDir}(FTP~*, char~*files)}
{
  Creats channel for directory list reading, described by argument \ts{files}.
}

\ttt{int \toindex{FtpRead}(FTP~*)}{
Reads character from data stream. If  \ts{ASCII} mode is set\footnote{By default} converts new line markers.
When the end of file is detected or channel is broken, returns \toindex{EOF}}

\ttt{\toindex{FtpGetString}(FTP~*, char~*str)}
{ Reads one string from data stream using \ts{FtpRead}}

\ttt{\toindex{FtpWrite}(FTP~*, char~c)}{
Writes single character to stream, if \ts{ASCII} mode is set converts new line markers.
When channel is broken, returns \toindex{EOF}}

\ttt{\toindex{FtpClose}(FTP~*)}
{Closes opened channel to server}

\section{Other commands for server}

\ttt{\toindex{FtpCommand}(FTP~*, char~*command, char~*param, int~ok1, ok2, ok3, ..., okN, EOF)}
{ Sends a command, composed from \ts{command} and \ts{param} using \ts{sprintf} function. 
Reads an answer from the server. 
When return code from the server is not included to \ts{ok-list}(\ts{ok1},\ts{ok2}...) the sign of code 
will be  inverted.}
}

\ttt{\toindex{FtpType}(FTP~*,char~*mode)}
{Sets transfer mode, such as \ts{``A''},\ts{''I''},\ts{''S''}}

\ttt{\toindex{FtpBinary}(FTP~*)}
{Sets binary mode}

\ttt{\toindex{FtpAscii}(FTP~*)}
{Sets \ts{ASCII} mode}


\ttt{\toindex{FtpMkdir}(FTP~*,char *dirname)}
{Makes  directory on server}

\ttt{\toindex{FtpChdir}(FTP~*,char *dirname)}
{Changes working directory on server}

\ttt{\toindex{FtpRm}(FTP~*,char *filename)}
{Removes file on server}

\ttt{char~*\toindex{FtpPwd}(FTP~*)}
{Returns the name of working directory on server}

\ttt{\toindex{FtpMove}(FTP~*,char *oldfilename, char *newfilename)}
{Renames file from \ts{oldfilename} to \ts{newfilename}}

\ttt{\toindex{FtpGetFile}(FTP~*,char *filename)}
{Sends start transfer file command to server. Does not make data channel}

\ttt{\toindex{FtpPutFile}(FTP~*,char *filename)}
{Sends start transfer file command to the server. Does not make data channel}

\ttt{\toindex{FtpPort}(FTP~*, int~a, int~b, int~c, int~d, int~e, int~f)}
{ A command for the server for making a new data channel. \ts{a.b.c.d} is an IP address of a client(i.e. your IP address), 
\ts{e*256+f} is a port number}

\section{Subprograms for sending/receiving control messages to/from server}

\ttt{\toindex{FtpSendMessage}(FTP~*, char~*message)}
{Sends a message to the server}

\ttt{int \toindex{FtpGetMessage}(FTP~*)}
{Receives a message from the server.}

\ttt{\toindex{FtpMessage}(int Number)}
{Gets a message by code.}

\section{High-level functions}

\ttt{FILE *\toindex{FtpFullOpen}(char *filename,char *mode)}
{  
Parses string \ts{filename}, which must contain a string in format or \\
\ts{host/user/password:filename} or \ts{filename},
what corresponds to remote or local file. The second argument is the type of opening, divided into two characters: 
first --- the mode of opening \ts{``r''}, \ts{``w''} or \ts{``a''}, second is the transfer type , if contains character \ts{``b''},
 then the mode is binary.
}

\ttt{STATUS FtpFullClose(FILE *stream)}
{Closes an opened file}

\newpage
\input rus.ind
\newpage
\tableofcontents
\end{document}

